---
target: Umo Office Convert
keywords: Umo Office Convert,office在线预览,wps在线预览,docx在线预览,word在线预览,pdf在线预览
description: 将 Office、WPS 等 40 余种办公文档转换为可在线查看的文档格式，可与 Umo Office Viewer 结合使用实现办公文档的在线预览。
---

# 数据库说明

本文描述 Umo Office Convert 服务所使用的数据库设计。该服务使用 MySQL 数据库来存储文档转换任务的相关信息。您也可以参考 MySQL 的实现，使用其他数据库来存储数据。

## 数据库配置

数据库配置信息存储在环境变量中，可以通过 `.env` 文件进行配置，详细配置项见：[环境变量-数据库配置](./evn#mysql-数据库配置)

## 表结构

### convert_tasks 表

该表用于存储文档转换任务的信息。

| 字段名         | 类型         | 说明                 | 约束                      |
| -------------- | ------------ | -------------------- | ------------------------- |
| id             | VARCHAR(255) | 任务 ID               | PRIMARY KEY               |
| filename       | VARCHAR(255) | 原始文件名           |                           |
| mime           | VARCHAR(255) | 文件 MIME 类型         |                           |
| size           | INT          | 原始文件大小(字节)   |                           |
| path           | VARCHAR(255) | 原始文件路径         |                           |
| hash           | VARCHAR(255) | 文件哈希值           |                           |
| converted_size | INT          | 转换后文件大小(字节) |                           |
| converted_path | VARCHAR(255) | 转换后文件路径       |                           |
| status         | VARCHAR(255) | 转换状态             |                           |
| converted_at   | TIMESTAMP    | 转换时间             | DEFAULT CURRENT_TIMESTAMP |

`status` 字段可能的值包括：

- `uploaded`: 文件已上传
- `converted`: 转换完成
- `failed`: 转换失败

## 数据库初始化

服务启动时会自动检查并创建所需的数据表。初始化代码位于 `src/utils/mysql.mjs` 文件中。

## 数据流程

1. 当通过接口获取到转换任务时，系统会创建一个新的转换任务记录。如果通过文件 `hash` 值匹配到已转换的任务，则不会创建新任务，从缓存中直接获取已转换的文件
2. 转换完成后，会更新转换后的文件信息和状态
3. 用户可以通过任务 ID 查询转换任务信息及结果

## 缓存机制

系统使用文件哈希值来实现缓存机制。当用户上传相同的文件时，系统会检查数据库中是否已存在相同哈希值的转换任务，如果存在且转换成功，则直接返回已转换的文件，避免重复转换。

## 数据备份建议

建议定期备份 `convert_tasks` 表数据，以防数据丢失。可以使用以下命令进行备份：

```bash
mysqldump -u [用户名] -p [数据库名] convert_tasks > convert_tasks_backup_$(date +%Y%m%d).sql
```
